#import <Foundation/Foundation.h>
#import "SFUEvent.h"
#import "NSArrayCustomSort.h"

/**
 * An SFUEventCollection is an object representing a
 * temporary collection of SFU events.
 *
 * @author      James Lin
 * @version     0.6.6
 * @since       0.0.1
 */
@interface SFUEventCollection : NSObject {
	NSMutableDictionary* eventDictionary; // A dictionary of SFU events
}

/**
 * Initialize the SFUEventCollection as an empty collection.
 *
 * @return  the initialized empty SFUEventCollection
 */
- (id)init;

/**
 * Initialize the SFUEventCollection with an array of SFU events.
 * 
 * @precondition  the events are all valid and unique
 * @param events  the array of events with which to initialize
 * @return        the initialized SFUEventCollection with specified events
 */
- (id)initWithEvents:(NSArray*)events;

/**
 * Add an SFU event to the collection.
 * 
 * @precondition  the event is unique in the collection
 * @param event   the event to add
 */
- (void)addEvent:(SFUEvent*)event;

/**
 * Add an array of SFU events to the collection.
 *
 * @precondition  the events are all unique in the collection
 * @param events  the array of events to add
 */
- (void)addEvents:(NSArray*)events;

/**
 * Add another SFU event collection to this collection.
 * 
 * @param eventCollection  the event collection to add to this collection
 */
- (void)addEventCollection:(SFUEventCollection*)eventCollection;

/**
 * Determine whether the given SFU event is in the collection.
 *
 * @param event  the event of which to check existence
 * @return       YES if the event is in the collection;
 *               NO otherwise.
 */
- (BOOL)containsEvent:(SFUEvent*)event;

/**
 * Retrieve size of collection.
 *
 * @return  the size of the collection as an integer
 */
- (int)size;

/**
 * Retrieve all SFU events in the collection.
 *
 * @return  an array of all SFU events in the collection
 */
- (NSArray*)getEvents;

/**
 * Find all SFU events whose heading or category contains
 * any keyword in the given space-delimited keyword string.
 *
 * @precondition   keyword string is not nil
 * @param keyword  the case-insensitive search keyword string
 * @return         an array of SFU events with suitable matches
 */
- (NSArray*)findEventsWithKeywordString:(NSString*)keyword;

/**
 * Find all SFU events whose heading or category contains
 * any or all of the keywords in the given keyword list.
 *
 * If matching by any keyword in the keyword list, an additional sort
 * will be performed on the resulting list after the completed query.
 * The resulting list of events will be in non-increasing order of 
 * the number of keywords matched.
 *
 * @precondition    keywords are not nil
 * @param keywords  the list of case-insensitive search keywords
 * @param matchAll  YES if all keywords in the keyword list must match;
 *                  NO if any keyword can match.
 * @return          an array of SFU events with suitable matches
 */
- (NSArray*)findEventsWithKeywords:(NSArray*)keywords 
				  matchAllKeywords:(BOOL)matchAll;

/**
 * Remove an SFU event from the collection.
 *
 * @param event  the event to remove
 */
- (void)removeEvent:(SFUEvent*)event;

/**
 * Empty the collection.
 */
- (void)clear;

@end